'.\" t
.TH "clrunapp" "1M" "Jun 26, 2006" "1\&.2\&.0"
.SH NAME
clrunapp \- Run application in Linuxha.net cluster

.SH SYNOPSIS
.TS
l.
clrunapp \fB-A|--application\fP \fIapp\fP [\fB--force\fP] [\fB--reallyforce\fP] [\fB--nodeps\fP]
         [\fB--preview\fP] [\fB--nologging\fP] [\fB--timeout\fP \fINN\fP] [\fB--node\fP \fINODE\fP]
         [\fB--reset\fP] [\fB--nochecksums\fP] [\fB--nolocking\fP]
       Start the specified application

clrunapp \fB-?\fP
       Show brief usage information
.TE

.SH DESCRIPTION
The \fIclrunapp(1M)\fP utility is the recommended tool for starting applications
in the cluster. It will actually make use of the underlying utility
\fIclstartapp(1M)\fP, but offers the following features not available
to that tool:

.TP 4
.B *
Is node independent - it will start the specified application locally or
on the remote node - whichever is deemed most suitable, (or specified
on the command line). 
.TP
.B *
Takes account of node preference information to decide which node is 
considered best (if both are valid for this application). This allows the
administrator to choose manual or dynamic application load balancing if
deemed suitable.
.TP
.B *
Can handle dependencies to ensure that any applications that must be running
prior to this package are started, and if not start them according to 
their node preferences.
.TP
.B *
Allows the actions of the command to be previewed so it is possible to
understand the potential impact of running such a command. This is 
particularly useful when applications dependencies are in use.
.TP
.B *
It can reset the fail-over settings to ensure the application will
start on either node of the cluster if it was previously halted due to
software related problems.
.SH ARGUMENTS
.TP 4
.B -A,--application
This is the only mandatory argument and it defines the application that
the administrator wishes to start.
.TP
.B -F,--force
This will pass the \fB--force\fP argument to the underlying \fIclstartapp(1M)\fP
command allowing the application to start if the cluster daemon is not 
present or the remote node is not available.
.TP
.B --reallyforce
This passes the \fB--reallyforce\fP argument to the \fIclstartapp(1M)\fP
utility ensuring that the application will start up on the specified node,
even under normally unwanted circumstances.

Currently this argument has no impact though may allow the application
to be started on a node with known stale data at some point in the
future.

.TP
.B --nodeps
Do not check the availability of any applications that this application
depends on - no other applications not currently running will be started when
this argument is used despite any application dependencies configured.
.TP
.B --nologging
Turn off the verbose option - normally the utility will ensure the 
\fI--verbose\fP option is passed to the \fIclstartapp(1M)\fP utility
which is recommended. However if you do not want logging in the 
standard log files, then use this argument.

Note: This also influences the call to start the Lems daemon - ensuring
that daemon for any application started also does not use verbose logging. 
.TP
.B --preview
Do not actually start any applications, but instead indicate what and
where the applications would be started, (useful if an application indicates
that is has dependencies on other applications).
.TP
.B --reset
Before checking which machines are suitable for running the specified 
application reset the list of valid nodes. This is necessary if the 
application has been halted because one or both nodes have had fail-overs 
due to software/network issues.
.TP
.B --localonly
THIS IS NOT YET IMPLEMENTED - only start any applications on the current
node, rather than considering the remote node as a suitable location,
even for dependent applications.
.TP
.B -T,--timeout
This defines the period in seconds that is given for the specified 
application to start. If not specified it will default to 30 seconds. If
other applications need to be started they will all be given the same
start-up time-out value.
.TP
.B --node
Indicates that the specified application should only consider the specified
node to start on. If this node is not valid (and the \fB--reset\fP flag
has not been specified) then the application will not be started.
.TP
.B --nochecksums
Normally if the cluster or application configuration file 
have been modified whilst the cluster is running the
checksums which are used to indicate the last sane and checked configuration 
will not be valid. In such instances many of the Linuxha.net commands, including
this will not will not function. If necessary the \fB--nochecksums\fP can be
used to overcome this until the cluster or application configuration are
next rebuilt.
.TP
.B --nolocking
Do not attempt to acquire resource locks via the \fIcllockd(1M)\fP locking
daemon (if it is running). For single application clusters this is possible
to reduce start-up times (very slightly).

.SH EXIT STATUS
The \fIclrunapp(1M)\fP utility makes use of many error codes, but in summary
it will return a non-zero number for an error or zero if the information
requested has been successfully processed.

.SH FILES
The Linuxha.net Administrators Guide contains a complete list of files 
that are important for starting and checking on the status of an 
application in the cluster.

The list below contains some of the more important ones only.

.TP 4
.B /var/log/cluster/cldaemon-clustername
This log contains the local cldaemon messages. The 'clustername'
portion is actually the name assigned to the cluster. The amount
of detail in here is determined by the use of the '--verbose'
option on the \fIcldaemon(1M)\fP command. 
.TP
.B /var/log/cluster/clstartapp-appname
The name which contains the log output of the specified application
when it starts up. In a similar way to the cluster log file, this
file contents depend on whether the '--verbose' option is used, and
of course when using the \fIclrunapp(1M)\fP command this option is 
turned on, (unless the \fB--nologging\fP argument was specified).

.SH SEE ALSO
.TS
l l.
clbuild(1M)	- Build / Validate cluster topology
clbuildapp(1M)	- Build / Synchronise cluster application 
cldeamon(1M)	- Cluster status Daemon
clform(1M)	- Form the cluster
clstartapp(1M)	- Start a clustered application
clstat(1M)	- Show cluster status information
clhaltapp(1M)	- Halt a clustered application
clconf.xml(5)	- Overall cluster topology configuration file
appconf.xml(5)	- Configuration of an application used by the cluster
.TE

.SH NOTES
If this program does fail the administrator is recommended to view
the cluster and application files, as described in the \fBFILES\fP
section above.

.SH AUTHOR
The \fIclrunapp(1M)\fP utility was written by Simon Edwards, 2003-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

